/*
 * Copyright 2009 Max Kugland
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.splink.deepsplink.navigation {
	import org.splink.library.IFinalizable;

	import flash.display.DisplayObject;

	/**
	 * An <code>IPageNavigationViewy</code> can register with an 
	 * <code>IPageNavigationController</code>. The view is provided with all 
	 * neccessary information to conveniently perform the job to render a navigation 
	 * based on the data provided as argument in it's <code>render</code> method.
	 * 
	 * @author Max Kugland
	 */
	public interface IPageNavigationView extends IFinalizable {
		/**
		 * Sets an <code>IPageNavigationController</code> implementation
		 * for the <code>IPageNavigationView</code> to work with.
		 * The controller enables the view to induce a page change.
		 * 
		 * @param controller the <code>IPageNavigationController</code>
		 */
		function setController(controller : IPageNavigationController) : void;

		/**
		 * Renders the view. 
		 * 
		 * @param childPageIds an <code>Array</code> of the ids of the child pages of the page.
		 * The render implementation probably renders a button for each of the childPage id's and
		 * if that button is clicked the a new gotoPage request is invoked to change from the current
		 * page to the page corresponding to the clicked button id.
		 */
		function render(childPageIds : Array) : void;

		/**
		 * Invoked if a navigation item needs highlighting. If an item is not
		 * directly selected, but the selected item is one of its children(...),
		 * <code>select</code> is also invoked with the id of the item which needs
		 * selection.
		 * 
		 * @param id the id of the item which is to be selected 
		 * @param pageParams the page parameters of the page change request
		 * @param changed a boolean value which indicates whether the page request 
		 * results in a page change or not
		 */
		function select(id : String, pageParams : Array = null, changed : Boolean = true) : void;

		/**
		 * @return the display in which the navigation is rendered
		 */
		function get display() : DisplayObject;
		/**
		 * Finalizes the view. The finalize method of registred navigation views 
		 * is automatically executed, when the page they are registered with 
		 * is finalized.
		 */
		// function finalize() : void;
	}
}
